home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / share / perl5 / Mail / Field / AddrList.pod < prev    next >
Encoding:
Text File  |  2008-07-29  |  3.5 KB  |  196 lines
  1. =head1 NAME
  2.  
  3. Mail::Field::AddrList - object representation of e-mail address lists
  4.  
  5. =head1 INHERITANCE
  6.  
  7.  Mail::Field::AddrList
  8.    is a Mail::Field
  9.  
  10. =head1 SYNOPSIS
  11.  
  12.   use Mail::Field::AddrList;
  13.  
  14.   $to   = Mail::Field->new('To');
  15.   $from = Mail::Field->new('From', 'poe@daimi.aau.dk (Peter Orbaek)');
  16.   
  17.   $from->create('foo@bar.com' => 'Mr. Foo', poe => 'Peter');
  18.   $from->parse('foo@bar.com (Mr Foo), Peter Orbaek <poe>');
  19.  
  20.   # make a RFC822 header string
  21.   print $from->stringify(),"\n";
  22.  
  23.   # extract e-mail addresses and names
  24.   @addresses = $from->addresses(); # strings
  25.   @names     = $from->names();     # strings
  26.   @addr      = $from->addr_list(); # Mail::Address objects (v2.00)
  27.  
  28.   # adjoin a new address to the list
  29.   $from->set_address('foo@bar.com', 'Mr. Foo');
  30.  
  31. =head1 DESCRIPTION
  32.  
  33. Defines parsing and formatting of address field, for the following
  34. fields: C<To>, C<From>, C<Cc>, C<Reply-To>, and C<Sender>.
  35.  
  36. All the normally used features of the address field specification of
  37. RFC2822 are implemented, but some complex (and therefore hardly ever used)
  38. constructs will not be inderstood.  Use Mail::Message::Field::Full
  39. in MailBox if you need full RFC compliance.
  40.  
  41. =head1 METHODS
  42.  
  43. =head2 Constructors
  44.  
  45. Mail::Field::AddrList-E<gt>B<combine>(FIELDS)
  46.  
  47. =over 4
  48.  
  49. See L<Mail::Field/"Constructors">
  50.  
  51. =back
  52.  
  53. Mail::Field::AddrList-E<gt>B<extract>(TAG, HEAD [, INDEX ])
  54.  
  55. =over 4
  56.  
  57. See L<Mail::Field/"Constructors">
  58.  
  59. =back
  60.  
  61. Mail::Field::AddrList-E<gt>B<new>(TAG [, STRING | OPTIONS])
  62.  
  63. =over 4
  64.  
  65. See L<Mail::Field/"Constructors">
  66.  
  67. =back
  68.  
  69. =head2 "Fake" constructors
  70.  
  71. $obj-E<gt>B<create>(OPTIONS)
  72.  
  73. =over 4
  74.  
  75. See L<Mail::Field/""Fake" constructors">
  76.  
  77. =back
  78.  
  79. $obj-E<gt>B<parse>
  80.  
  81. =over 4
  82.  
  83. See L<Mail::Field/""Fake" constructors">
  84.  
  85. =back
  86.  
  87. =head2 Accessors
  88.  
  89. $obj-E<gt>B<set>(OPTIONS)
  90.  
  91. =over 4
  92.  
  93. See L<Mail::Field/"Accessors">
  94.  
  95. =back
  96.  
  97. $obj-E<gt>B<stringify>
  98.  
  99. =over 4
  100.  
  101. See L<Mail::Field/"Accessors">
  102.  
  103. =back
  104.  
  105. $obj-E<gt>B<tag>
  106.  
  107. Mail::Field::AddrList-E<gt>B<tag>
  108.  
  109. =over 4
  110.  
  111. See L<Mail::Field/"Accessors">
  112.  
  113. =back
  114.  
  115. =head2 Smart accessors
  116.  
  117. $obj-E<gt>B<addr_list>
  118.  
  119. =over 4
  120.  
  121. Returns the collected L<Mail::Address|Mail::Address> objects.
  122.  
  123. =back
  124.  
  125. $obj-E<gt>B<addresses>
  126.  
  127. =over 4
  128.  
  129. Returns a list if email addresses, found in the field content.
  130.  
  131. =back
  132.  
  133. $obj-E<gt>B<names>
  134.  
  135. =over 4
  136.  
  137. Returns a list of nicely formatted named, for each of the addresses
  138. found in the content.
  139.  
  140. =back
  141.  
  142. $obj-E<gt>B<set_address>(EMAIL, NAME)
  143.  
  144. =over 4
  145.  
  146. Add/replace an EMAIL address to the field.
  147.  
  148. =back
  149.  
  150. $obj-E<gt>B<text>([STRING])
  151.  
  152. =over 4
  153.  
  154. See L<Mail::Field/"Smart accessors">
  155.  
  156. =back
  157.  
  158. =head1 DETAILS
  159.  
  160. =head1 DIAGNOSTICS
  161.  
  162. Error: Undefined subroutine <method> called
  163.  
  164. =over 4
  165.  
  166. Mail::Field objects use autoloading to compile new functionality.
  167. Apparently, the mehod called is not implemented for the specific
  168. class of the field object.
  169.  
  170. =back
  171.  
  172. =head1 SEE ALSO
  173.  
  174. This module is part of the MailTools distribution,
  175. F<http://perl.overmeer.net/mailtools/>.
  176.  
  177. =head1 AUTHORS
  178.  
  179. The MailTools bundle was developed by Graham Barr.  Later, Mark
  180. Overmeer took over maintenance without commitment to further development.
  181.  
  182. Mail::Cap by Gisle Aas E<lt>aas@oslonett.noE<gt>.
  183. Mail::Field::AddrList by Peter Orbaek E<lt>poe@cit.dkE<gt>.
  184. Mail::Mailer and Mail::Send by Tim Bunce E<lt>Tim.Bunce@ig.co.ukE<gt>.
  185. For other contributors see ChangeLog.
  186.  
  187. =head1 LICENSE
  188.  
  189. Copyrights 1995-2000 Graham Barr E<lt>gbarr@pobox.comE<gt> and
  190. 2001-2007 Mark Overmeer E<lt>perl@overmeer.netE<gt>.
  191.  
  192. This program is free software; you can redistribute it and/or modify it
  193. under the same terms as Perl itself.
  194. See F<http://www.perl.com/perl/misc/Artistic.html>
  195.  
  196.